home *** CD-ROM | disk | FTP | other *** search
/ Aminet 31 / Aminet 31 (1999)(Schatztruhe)[!][Jun 1999].iso / Aminet / comm / thor / thor26_api.lha / README.API
Encoding:
Text File  |  1998-02-19  |  6.3 KB  |  130 lines
  1. 980218                  Thor 2.6 API documentation
  2.  
  3.   Copyright © 1994-1998 Ultima Thule Software, All Rights Reserved.
  4.         Authors: Eivind Nordseth, Kjell Irgens, Petter Nilsen
  5.  
  6. This  API documentation package is NOT public domain, but it is freely
  7. distributable.   In  other  word  it  is  FreeWare.   (Note:   Thor is
  8. ShareWare.)  This  means  that  you  can  copy  this API documentation
  9. package and give it to all your friends, upload it to a BBS or include
  10. it  in  a  PD-library.   The  only  restrictions  are:   All the files
  11. included  in  this  archive  must  be  in  their original form without
  12. additions,   deletions   or  modifications  of  any  kind.   Thor  API
  13. documentation  may  not  be  distributed  for  profit.  Only a nominal
  14. charge  may  be  associated  with  its  distribution.   The  Thor  API
  15. documentation  is  provided  "AS IS" without warranty of any kind, and
  16. the  authors  is  not responsible for any damage this software may do.
  17. (Just in case :-)
  18.  
  19. Do not release any modifications of the code examples included in this
  20. package.   If  you  have  suggestions  for  code  improvements, please
  21. contact the authors.
  22.  
  23.  
  24. INTRODUCTION
  25. ~~~~~~~~~~~~
  26. The Thor API documentation package consists of:
  27.  
  28. o docs/bbsread.doc  -  Autodoc for V5 of bbsread.library.
  29. o include/#?        -  Include files for V5 of bbsread.library.
  30. o parsemsg/#?       -  Source code of a message parser, which adds messages
  31.                        from ABBS/MBBS to the message database. Will also 
  32.                        parse newfiles lists and conference lists.
  33. o scriptserv/#?     -  Source code for a script server. This program is 
  34.                        used by the ABBS/MBBS Ncomm scripts to gain knowledge
  35.                        of the different events to do. It has also other 
  36.                        features used by this NComm script.
  37. o packhippo/?#      -  Source code for an events packer, which makes upload 
  38.                        packets in Hippo format.
  39. o common/#?         -  Some small code stubs which are common for scriptserv
  40.                        and parsemsg.
  41. o WatchTHOR/#?      -  Source code for the WatchTHOR mail notification
  42.                        utility. 
  43.  
  44. Some   of  the  source  uses  utgui.library  for  displaying  progress
  45. requesters.   The  api for utgui.library is not included here.  (Since
  46. the utgui.library probably will be obsolete in later versions of Thor,
  47. the  docs  for  utgui.library is not released.) If you want to compile
  48. the soures which uses utgui.library, you must comment out all calls to
  49. utgui.library.
  50.  
  51.  
  52. HOW TO USE
  53. ~~~~~~~~~~
  54. We have not included any detailed step by step guide to how to program
  55. utilites and modules for Thor.
  56.  
  57. Some general advices:
  58.  
  59. o You should read the source code provided, docs/bbsread.doc and
  60.   include/libraries/bbsread.h carefully before doing any programming.
  61.  
  62. o If you are to write a module for Thor, you should first make a working
  63.   message parser. After the parser is up and running, you should set up the
  64.   event configuration for the events you want to support, and then make a
  65.   event packer.
  66.  
  67. o If you are uncertain of how to use any of the provided functions, look
  68.   into the source code examples to see how thay are used there. If you
  69.   still are uncertain, send us an email and we'll try to answer your
  70.   questions.
  71.  
  72. If  you  have  any  questions regarding the use of the Thor API we are
  73. reachable on the Thor support email address:  thor@thule.no
  74.  
  75.  
  76. HISTORY
  77. ~~~~~~~
  78. 951105 - Initial release of the API documentation
  79. 950524 - THOR 2.3 API documentation, no changes except for the archive name
  80. 951020 - THOR 2.4 API documentation, minor header files changes
  81. 970825 - THOR 2.5 API documentation, changes:
  82.   - Length of paths for UnArchive() and Archive() has been doubled to 500
  83.     characters.
  84.   - Forwarded messages will not be purged on pack/purge before the event
  85.     has been executed and the events purged. MDF_REFERENCED is the private
  86.     flag added to messages that should not be purged.
  87.   - API change allows for creating a list of file attachments at pack/purge
  88.     time, so they can be browsed later for copying, deletion etc. New tag
  89.     PD_AttachmentList to PackDataFile() added for this purpose.
  90.   - WBRK_MarkDeleted can be set on a kill, which will really delete a
  91.     message if it matches a kill. WriteBRMessage() will not write the message
  92.     to the database if a match with this tag is found. NOTE: This introduces
  93.     a slight API change in in what WriteBRMessage() returns. If possible, 
  94.     do not rely on this return value if it's anything else but 0, which 
  95.     means failure. -1 is returned on messages that are not added to the 
  96.     database due to a kill match on the above tag.
  97.   - BRKILL_Description tag added to the kill interface.
  98.   - UnArchive() will now fail if the archive is 0 bytes.
  99.   - The temp directory when packing will be created now if it doesn't exist.
  100.   - Messages with MDF_DELETED flag set can still be read, unless the
  101.     MDF_UNRECOVERABLE flag is set.
  102.   - New public function SortMessageArray() added.
  103.   - Replaced the internal function for sorting lists with a new one based 
  104.     on the mergesort algoritm, which is a lot faster.
  105.   - Subject sorting will also make sure the messages are sorted on date, so
  106.     the oldest messages comes first.
  107.   - 2 new tags added, UBRM_ClearMarked and UBRM_SetMarked.
  108.  
  109. 980218 - THOR 2.6 API documentation, changes:
  110.   - Bumped the version to 6.
  111.   - confdata.cd_ExtraFlags field added with CDXF_ONLYHEADERS as the only flag
  112.     for now.
  113.   - confinternal.ci_NumQueued added that will contain the number of queued
  114.     messages in this conference.
  115.   - confdata.cd_HighMark added that can contain the high mark for messages or
  116.     headers collected for this conference.
  117.   - New message flags:
  118.        MDF_QUEUED - Message is queued for future collection of the main body
  119.                     and header
  120.        MDF_EMPTY_BODY - Message consists of only a header and no full body
  121.  
  122.   - New tag for ConfigConf(): CC_HighMark
  123.   - New tags for WriteBRMessage(): BRMSG_MsgSize, BRMSG_SpecialID, BRMSG_ErrorString,
  124.     BRMSG_TextPartUniqueID, BRMSG_TextPartFilename, WBRMSG_Queued and WBRMSG_EmptyBody.
  125.   - Many of the tags for WriteBRMessage() can now also be used in UpdateBRMessage().
  126.   - New tags for UpdateBRMessage(): UBRM_SetQueued, UBRM_ClearQueued, UBRM_UpdateHeaders
  127.     and UBRM_UpdateText.
  128.   - Will search in message-id too as default in SearchBRMessage()
  129.   - Comments on kills works as they should.
  130.